<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<!-- Copyright 1997 The Open Group, All Rights Reserved -->
<title>connect</title>
</head><body bgcolor=white>
<center>
<font size=2>
The Single UNIX &reg; Specification, Version 2<br>
Copyright &copy; 1997 The Open Group

</font></center><hr size=2 noshade>
<h4>NAME</h4><blockquote>
connect - connect a socket
</blockquote><h4>SYNOPSIS</h4><blockquote>
<pre><code>

#include &lt;<a href="syssocket.h.html">sys/socket.h</a>&gt;

int connect(int <I>socket</I>, const struct sockaddr *<I>address</I>,
    socklen_t <I>address_len</I>);
</code>
</pre>
</blockquote><h4>DESCRIPTION</h4><blockquote>
The
<i>connect()</i>
function requests a connection to be made on a socket.  The function takes the
following arguments:
<dl compact>

<dt><I>socket</I><dd>Specifies the file descriptor associated with the socket.

<dt><I>address</I><dd>Points to a <B>sockaddr</B> structure containing the peer address.  The length
and format of the address depend on the address family of the socket.

<dt><I>address_len</I><dd>Specifies the length of the <B>sockaddr</B> structure
pointed to by the <I>address</I> argument.

</dl>
<p>
If the socket has not already been bound to a local address, 
<i>connect()</i>
will bind it to an address which, unless the socket's address family 
is AF_UNIX, is an unused local address.
<p>
If the initiating socket is not connection-mode, then
<i>connect()</i>
sets the socket's peer address, but no connection is made.  For SOCK_DGRAM
sockets, the peer address identifies where all datagrams are sent on
subsequent
<i><a href="send.html">send()</a></i>
calls, and limits the remote sender for subsequent
<i><a href="recv.html">recv()</a></i>
calls.  If <I>address</I> is a null address for the protocol, the socket's peer
address will be reset.
<p>
If the initiating socket is connection-mode, then
<i>connect()</i>
attempts to establish a connection to the address specified by the
<I>address</I> argument.
<p>
If the connection cannot be established immediately and O_NONBLOCK is not set
for the file descriptor for the socket,
<i>connect()</i>
will block for up to an unspecified timeout interval until the
connection is established.  If the timeout interval expires before the
connection is established,
<i>connect()</i>
will fail and the connection attempt will be aborted.  If
<i>connect()</i>
is interrupted by a signal that is caught while blocked waiting to establish a
connection,
<i>connect()</i>
will fail and set <I>errno</I> to [EINTR], but the connection request will not
be aborted, and the connection will be established asynchronously.
<p>
If the connection cannot be established immediately and O_NONBLOCK is set for
the file descriptor for the socket,
<i>connect()</i>
will fail and set <I>errno</I> to [EINPROGRESS], but the connection request
will not be aborted, and the connection will be established asynchronously.
Subsequent calls to
<i>connect()</i>
for the same socket, before the connection is established, will fail and set
<I>errno</I> to [EALREADY].
<p>
When the connection has been established asynchronously,
<i><a href="select.html">select()</a></i>
and
<i><a href="poll.html">poll()</a></i>
will indicate that the file descriptor for the socket is ready for writing.
<p>
The socket in use may require the process to have appropriate
privileges to use the
<i>connect()</i>
function.
</blockquote><h4>RETURN VALUE</h4><blockquote>
Upon successful completion,
<i>connect()</i>
returns 0.  Otherwise, -1 is returned and <I>errno</I> is set to
indicate the error.
</blockquote><h4>ERRORS</h4><blockquote>
The
<i>connect()</i>
function will fail if:
<dl compact>

<dt>[EADDRNOTAVAIL]<dd>The specified address is not available from the local machine.

<dt>[EAFNOSUPPORT]<dd>The specified address is not a valid address for the address family of the
specified socket.

<dt>[EALREADY]<dd>A connection request is already in progress for the specified socket.

<dt>[EBADF]<dd>The <I>socket</I> argument is not a valid file descriptor.

<dt>[ECONNREFUSED]<dd>The target address was not listening for connections or refused the connection
request.

<dt>[EFAULT]<dd>The address parameter can not be accessed.

<dt>[EINPROGRESS]<dd>O_NONBLOCK is set for the file descriptor for the socket and the
connection cannot be immediately established; the connection will be
established asynchronously.

<dt>[EINTR]<dd>The attempt to establish a connection was interrupted by delivery of a signal
that was caught; the connection will be established asynchronously.

<dt>[EISCONN]<dd>The specified socket is connection-mode and is already connected.

<dt>[ENETUNREACH]<dd>No route to the network is present.

<dt>[ENOTSOCK]<dd>The <I>socket</I> argument does not refer to a socket.

<dt>[EPROTOTYPE]<dd>The specified address has a different type than the socket bound to the
specified peer address.

<dt>[ETIMEDOUT]<dd>The attempt to connect timed out before a connection was made.

</dl>
<p>
If the address family of the socket is AF_UNIX, then
<i>connect()</i>
will fail if:
<dl compact>

<dt>[EIO]<dd>An I/O error occurred while reading from or writing to the file system.

<dt>[ELOOP]<dd>Too many symbolic links were encountered in translating the pathname in
<I>address</I>.

<dt>[ENAMETOOLONG]<dd>A component of a pathname exceeded {NAME_MAX} characters, or an
entire pathname exceeded {PATH_MAX} characters.

<dt>[ENOENT]<dd>A component of the pathname does not name an existing file
or the pathname is an empty string.

<dt>[ENOTDIR]<dd>A component of the path prefix of the pathname in <I>address</I> is not a
directory.

</dl>
<p>
The
<i>connect()</i>
function may fail if:
<dl compact>

<dt>[EACCES]<dd>Search permission is denied for a component of the path prefix; or
write access to the named socket is denied.

<dt>[EADDRINUSE]<dd>Attempt to establish a connection that uses addresses that are already in use.

<dt>[ECONNRESET]<dd>Remote host reset the connection request.

<dt>[EHOSTUNREACH]<dd>The destination host cannot be reached (probably because the host is down or
a remote router cannot reach it).

<dt>[EINVAL]<dd>The <I>address_len</I> argument is not a valid length for the address family;
or invalid address family in sockaddr structure.

<dt>[ENAMETOOLONG]<dd>Pathname resolution of a symbolic link produced an intermediate result whose
length exceeds {PATH_MAX}.

<dt>[ENETDOWN]<dd>The local interface used to reach the destination is down.

<dt>[ENOBUFS]<dd>No buffer space is available.

<dt>[ENOSR]<dd>There were insufficient STREAMS resources available to complete the operation.

<dt>[EOPNOTSUPP]<dd>The socket is listening and can not be connected.

</dl>
</blockquote><h4>APPLICATION USAGE</h4><blockquote>
If
<i>connect()</i>
fails, the state of the socket is unspecified.  Portable applications should
close the file descriptor and create a new socket before attempting to
reconnect.
</blockquote><h4>SEE ALSO</h4><blockquote>
<i><a href="accept.html">accept()</a></i>,
<i><a href="bind.html">bind()</a></i>,
<i><a href="close.html">close()</a></i>,
<i><a href="getsockname.html">getsockname()</a></i>,
<i><a href="poll.html">poll()</a></i>,
<i><a href="select.html">select()</a></i>,
<i><a href="send.html">send()</a></i>,
<i><a href="shutdown.html">shutdown()</a></i>,
<i><a href="socket.html">socket()</a></i>,
<i><a href="syssocket.h.html">&lt;sys/socket.h&gt;</a></i>.
</blockquote><hr size=2 noshade>
<center><font size=2>
UNIX &reg; is a registered Trademark of The Open Group.<br>
Copyright &copy; 1997 The Open Group
<br> [ <a href="../index.html">Main Index</a> | <a href="../xshix.html">XSH</a> | <a href="../xcuix.html">XCU</a> | <a href="../xbdix.html">XBD</a> | <a href="../cursesix.html">XCURSES</a> | <a href="../xnsix.html">XNS</a> ]

</font></center><hr size=2 noshade>
</body></html>
